home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 1.iso / ARGONET / PD / PROGRAMMING / LCLINT2.SPK / docs / ROS-txt < prev   
Text File  |  1996-11-15  |  10KB  |  233 lines
  1.                 LCLint 2.2a+
  2.             RISC OS port version 0.01
  3.  
  4. LCLint is a tool for statically checking C source code prior to compilation.
  5. Full details on the use of LCLint can be found in the User's Guide. This
  6. should be available, in HTML and plain text format, from the same place that
  7. this archive came from or from the LCLint Home page:-
  8.  
  9. http://larch-www.lcs.mit.edu:8001/larch/lclint/
  10.  
  11. This file is designed to document any changes that were necessary to port
  12. LCLint to RISC OS.
  13.  
  14. Filenames
  15. ---------
  16. Standard RISC OS filenames are expected, although some filename processing is
  17. carried out to allow similar naming conventions to the C compiler. Therefore,
  18. where MSDOS style extensions are used, they are converted to directory names.
  19. For example, a file named:-
  20.  
  21. abstract.c
  22.  
  23. with be converted to:-
  24.  
  25. c.abstract
  26.  
  27. The c extension is converted to a directory called c as is normal for RISC
  28. OS. This is also true if any pathname is given, so the names:-
  29.  
  30. sources.abstract.c
  31. sources:abstract.lcl
  32.  
  33. will be converted to:-
  34.  
  35. sources.c.abstract
  36. sources:lcl.abstract
  37.  
  38. respectively before being passed to the filing system.
  39.  
  40. The above filename processing applies to c, h and lcl files only. It may be
  41. extended to other filetypes in a later release if this is found to be useful.
  42.  
  43. Installation of LCLint
  44. ----------------------
  45. Before attempting to use LCLint, all files within the archive should be
  46. extracted to an empty directory on a hard disc. This document will assume
  47. that the directory is called lclint. This directory should then contain:-
  48.  
  49. lclint            = the installation directory
  50.   |
  51.   |-!Setup        = Obey file for run path and system variables
  52.   |
  53.   |-lclintrc        = options file (can be altered as required)
  54.   |
  55.   |-lclint        = the executable
  56.   |
  57.   |-imports        = directory containing standard library files
  58.   |
  59.   |-lib            = directory containing standard lclint library files
  60.   |
  61.   |-test        = directory containing test suite
  62.   |
  63.   |-docs        = directory containing User's guide as a text file
  64.               and this file in ASCII and EasiWriter format
  65.  
  66. Using LCLint under RISC OS
  67. --------------------------
  68. Double-clicking the obey file called !Setup will place LCLint on the run path
  69. so that it can be found easily. !Setup also creates three system variables
  70. that LCLint requires, which are closely modelled on the original ones used in
  71. the Unix environment. They are:-
  72.  
  73. Larch$PathDir
  74. LCLint$ImportDir - these define the path names of the LCLint standard
  75.                    libraries
  76.  
  77. LCLint$CPPCmd    - this defines the command used to invoke the C
  78.                    preprocessor. This can be changed to use a different
  79.                    preprocessor such as gcc or perhaps decus-cpp (the
  80.                    latter however has not been tested).
  81.  
  82. Please note that if any changes are made to this obey file, they will not be
  83. implemented unless the file is double-clicked again.
  84.  
  85. LCLint can be used from a makefile as shown by the test suite in this
  86. distribution.
  87.  
  88. Alternatively, it is recommended that it be run within a taskwindow where the
  89. results can be caught and saved if necessary. The taskwindow should be
  90. allocated enough memory to run both LCLint and the C preprocessor at the same
  91. time not forgetting to allow for the data they will process. It should be
  92. noted that the unsqueezed size of LCLint is currently 1054K. I have found
  93. that most of the test suite source code needs 3MB, but the database examples
  94. need about 5MB. The Currently Selected Directory (CSD) should be set to the
  95. one that contains the c and h directories. This can easily be done by
  96. typing:-
  97.  
  98. dir<SPACE>
  99.  
  100. in the taskwindow and then shift-dragging the relevant directory to the
  101. taskwindow where the full pathname of the directory will be inserted after
  102. the dir command. Pressing RETURN will then execute the command.
  103.  
  104. If the switch -nof is NOT given on the command line, then additional options
  105. are read from the file named lclintrc in the home directory of LCLint.
  106.  
  107. Additional switches
  108. -------------------
  109. In addition to the switches described in the User's Guide, this port of
  110. LCLint also provides -throwback (on command line only) which enables the
  111. transfer of errors messages to a text editor. The ddeutils modules is
  112. required for the use of this facility.
  113.  
  114. Trouble-shooting
  115. ----------------
  116. If LCLint complains that it is unable to open a temp file, then ensure that
  117. the compiler is visible on the command, i.e. that it is in the run path or
  118. in the library directory. For example, GCC requires that you double-click on
  119. !GCC, but be aware that this resets the CSD. If the compiler is not on the
  120. same filing system as your work directory, then alter LCLint$CPPcmd to add
  121. the filing system to the beginning of the command, e.g. adfs:cc -E. Also
  122. ensure, if the compiler is not being called, that there is enough memory for
  123. it to be loaded.
  124.  
  125. If your source code #includes library headers, make sure that you use the -I
  126. switch so that LCLint can tell the preprocessor where it can find them.
  127.  
  128. If the compiler complains about not being able to find a standard header file
  129. , make sure that C: has been defined. 
  130.  
  131. Known problems
  132. --------------
  133. A parse error is generated when parsing the Acorn C standard headers
  134. preprocessed with Acorn C/C++. This seems to be caused by the line #pragma
  135. force_top_level. There are two ways to overcome this, either use the
  136. +trytorecover switch or alter the header files so that the #pragma is defined
  137. out when LCLint is in use, i.e.
  138.  
  139. #ifndef __LCLINT__
  140. #pragma force_top_level
  141. #endif
  142.  
  143. The __LCLINT__ macro is automatically defined and passed to the
  144. preprocessor by LCLint. The problem does not exist when GCC is used as the
  145. preprocessor as it does not expand the Acorn C/C++ #pragmas.
  146.  
  147. The use of the hash character (#) on the command line causes problems.
  148. Specifically the command line seems to be truncated at the hash character
  149. before being passed to LCLint. Because of this, the two targets in the test
  150. suite that depend on this will fail. These are commentchar and prefixes. The
  151. use of the hash character in an rc file is unaffected.
  152.  
  153. Temporary files are not always deleted from the scrap directory. This is an
  154. isolated problem caused by a file being opened and not closed properly.
  155. Although all files that were opened by a particular incarnation of LCLint are
  156. closed by it on it's exit, this occurs after LCLint attempts to delete it and
  157. so the deletion fails.
  158.  
  159. When using Acorn C/C++ as the preprocessor, errors in c files are usually
  160. reported one line greater than where they really are. Header files do not
  161. seem to be affected by this. This is somehow caused by the #line directives
  162. generated by Acorn C/C++ in the preprocessed output either having the wrong
  163. line numbers or being on the wrong line. I did try to fix this in LCLint by
  164. testing for Acorn C/C++ and adjusting the line numbers whenever a #line
  165. directive was encountered, but only had partial success. I decided it was
  166. better to be consistently wrong rather than sometimes right.
  167.  
  168. Notes about the test suite
  169. --------------------------
  170. The directory structure of the test suite in this distribution is slightly
  171. different to the original due to the limit of 77 files per directory imposed
  172. by RISC OS. This mainly affects the c directory holding the source files. As
  173. a result of this it was necessary to split the test directory into two,
  174. test_a and test_b, so that two c directories could exist to hold the source
  175. files. This has meant that there is some duplication in the files (but not a
  176. lot) and that the makefiles have had to be altered to take the different
  177. directory structure into account.
  178.  
  179. Also due to a RISC OS limitation, some of the longer filenames have been
  180. truncated to ten characters, but in practice should still be recognisable.
  181.  
  182. Assuming that AMU and make have been seen by the filer and !Setup has been
  183. double-clicked to place lclint on your run path, the tests can be executed by
  184. typing the following:-
  185.  
  186. dir <path>.lclint.test
  187. amu
  188.  
  189. where <path> is the pathname of the directory where the lclint directory is
  190. stored. If using a taskwindow (which is recommended) then the test directory
  191. can be shift-dragged to it. The command amu executes the makefile in this
  192. directory which automatically executes makefiles for test_a, db1, db2, db3
  193. (which are all in test_a), test_b and tests2_2 (which is in test_b).
  194.  
  195. Issuing the command:-
  196.  
  197. amu clean
  198.  
  199. will delete all files and directories that were created during execution of
  200. the above make files.
  201.  
  202. The first and third tests of the rc target in test_b.makefile fail because of
  203. two odd macros.
  204.  
  205. When executing the makefile for any of the three database examples, db1, db2
  206. or db3, creation of the LCS file for dbase.c more often than not generates a
  207. free() failed error. This does not affect the creation of the file and
  208. execution of the makefile will continue unaffected.
  209.  
  210. When checking db3, lots of errors may be generated for the standard library
  211. headers especially for Acorn C/C++. This is because db3 is checked using the
  212. +strict flag which forces LCLint to use a stricter version of it's standard
  213. library. This version of the LCLint standard library does not match up with
  214. the header files for Acorn C/C++, hence the extra code errors. These can be
  215. ignored.
  216.  
  217. A note about the HTML format User's Guide
  218. -----------------------------------------
  219. Due to the number of files that make up the HTML User's Guide and the length
  220. of the filenames, it is not practical to extract it from it's archive. It is
  221. therefore recommended that it is used whilst still archived.
  222.  
  223. Finally
  224. -------
  225. Please report any bugs or other problems to me at the Email address below.
  226. If an error occurs that requests that you report it to
  227. lclint-bug@larch.lcs.mit.edu, please report it to me first in case it is
  228. specific to the RISC OS version. Also please ensure that they are not the
  229. result of low memory or a missing compiler.
  230.  
  231. Lee Noar
  232. leenoar@argonet.co.uk
  233.